<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.14"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>QHotkey: /home/sky/Programming/QtLibraries/QHotkey/README.md Source File</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">QHotkey
   &#160;<span id="projectnumber">1.2.2</span>
   </div>
   <div id="projectbrief">A global shortcut/hotkey for Desktop Qt-Applications</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.14 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
</div><!-- top -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">/home/sky/Programming/QtLibraries/QHotkey/README.md</div>  </div>
</div><!--header-->
<div class="contents">
<div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno">    1</span>&#160;# QHotkey</div><div class="line"><a name="l00002"></a><span class="lineno">    2</span>&#160;A global shortcut/hotkey for Desktop Qt-Applications.</div><div class="line"><a name="l00003"></a><span class="lineno">    3</span>&#160;</div><div class="line"><a name="l00004"></a><span class="lineno">    4</span>&#160;The QHotkey is a class that can be used to create hotkeys/global shortcuts, aka shortcuts that work everywhere, independent of the application state. This means your application can be active, inactive, minimized or not visible at all and still receive the shortcuts.</div><div class="line"><a name="l00005"></a><span class="lineno">    5</span>&#160;</div><div class="line"><a name="l00006"></a><span class="lineno">    6</span>&#160;## Features</div><div class="line"><a name="l00007"></a><span class="lineno">    7</span>&#160;- Works on Windows, Mac and X11</div><div class="line"><a name="l00008"></a><span class="lineno">    8</span>&#160;- Easy to use, can use `QKeySequence` for easy shortcut input</div><div class="line"><a name="l00009"></a><span class="lineno">    9</span>&#160;- Supports almost all common keys (Depends on OS &amp; Keyboard-Layout)</div><div class="line"><a name="l00010"></a><span class="lineno">   10</span>&#160;- Allows direct input of Key/Modifier-Combinations</div><div class="line"><a name="l00011"></a><span class="lineno">   11</span>&#160;- Supports multiple QHotkey-instances for the same shortcut (with optimisations)</div><div class="line"><a name="l00012"></a><span class="lineno">   12</span>&#160;- Thread-Safe - Can be used on all threads (See section Thread safety)</div><div class="line"><a name="l00013"></a><span class="lineno">   13</span>&#160;- Allows usage of native keycodes and modifiers, if needed</div><div class="line"><a name="l00014"></a><span class="lineno">   14</span>&#160;</div><div class="line"><a name="l00015"></a><span class="lineno">   15</span>&#160;**Note:** For now Wayland is not supported, as it is simply not possible to register a global shortcut with wayland. For more details, or possible Ideas on how to get Hotkeys working on wayland, see [Issue #14](https://github.com/Skycoder42/QHotkey/issues/14).</div><div class="line"><a name="l00016"></a><span class="lineno">   16</span>&#160;</div><div class="line"><a name="l00017"></a><span class="lineno">   17</span>&#160;## Installation</div><div class="line"><a name="l00018"></a><span class="lineno">   18</span>&#160;The package is providet as qpm  package, [`de.skycoder42.qhotkey`](https://www.qpm.io/packages/de.skycoder42.qhotkey/index.html). You can install it either via qpmx (preferred) or directly via qpm.</div><div class="line"><a name="l00019"></a><span class="lineno">   19</span>&#160;</div><div class="line"><a name="l00020"></a><span class="lineno">   20</span>&#160;### Via qpmx</div><div class="line"><a name="l00021"></a><span class="lineno">   21</span>&#160;[qpmx](https://github.com/Skycoder42/qpmx) is a frontend for qpm (and other tools) with additional features, and is the preferred way to install packages. To use it:</div><div class="line"><a name="l00022"></a><span class="lineno">   22</span>&#160;</div><div class="line"><a name="l00023"></a><span class="lineno">   23</span>&#160;1. Install qpmx (See [GitHub - Installation](https://github.com/Skycoder42/qpmx#installation))</div><div class="line"><a name="l00024"></a><span class="lineno">   24</span>&#160;2. Install qpm (See [GitHub - Installing](https://github.com/Cutehacks/qpm/blob/master/README.md#installing), for **windows** see below)</div><div class="line"><a name="l00025"></a><span class="lineno">   25</span>&#160;3. In your projects root directory, run `qpmx install de.skycoder42.qhotkey`</div><div class="line"><a name="l00026"></a><span class="lineno">   26</span>&#160;</div><div class="line"><a name="l00027"></a><span class="lineno">   27</span>&#160;### Via qpm</div><div class="line"><a name="l00028"></a><span class="lineno">   28</span>&#160;</div><div class="line"><a name="l00029"></a><span class="lineno">   29</span>&#160;1. Install qpm (See [GitHub - Installing](https://github.com/Cutehacks/qpm/blob/master/README.md#installing), for **windows** see below)</div><div class="line"><a name="l00030"></a><span class="lineno">   30</span>&#160;2. In your projects root directory, run `qpm install de.skycoder42.qhotkey`</div><div class="line"><a name="l00031"></a><span class="lineno">   31</span>&#160;3. Include qpm to your project by adding `include(vendor/vendor.pri)` to your `.pro` file</div><div class="line"><a name="l00032"></a><span class="lineno">   32</span>&#160;</div><div class="line"><a name="l00033"></a><span class="lineno">   33</span>&#160;Check their [GitHub - Usage for App Developers](https://github.com/Cutehacks/qpm/blob/master/README.md#usage-for-app-developers) to learn more about qpm.</div><div class="line"><a name="l00034"></a><span class="lineno">   34</span>&#160;</div><div class="line"><a name="l00035"></a><span class="lineno">   35</span>&#160;**Important for Windows users:** QPM Version *0.10.0* (the one you can download on the website) is currently broken on windows! It&#39;s already fixed in master, but not released yet. Until a newer versions gets released, you can download the latest dev build from here:</div><div class="line"><a name="l00036"></a><span class="lineno">   36</span>&#160;- https://storage.googleapis.com/www.qpm.io/download/latest/windows_amd64/qpm.exe</div><div class="line"><a name="l00037"></a><span class="lineno">   37</span>&#160;- https://storage.googleapis.com/www.qpm.io/download/latest/windows_386/qpm.exe</div><div class="line"><a name="l00038"></a><span class="lineno">   38</span>&#160;</div><div class="line"><a name="l00039"></a><span class="lineno">   39</span>&#160;## Usage</div><div class="line"><a name="l00040"></a><span class="lineno">   40</span>&#160;The general usage is to create QHotkey instances for specific hotkeys, register them and then simply connect to the signal emitted once the hotkey is pressed.</div><div class="line"><a name="l00041"></a><span class="lineno">   41</span>&#160;</div><div class="line"><a name="l00042"></a><span class="lineno">   42</span>&#160;### Example</div><div class="line"><a name="l00043"></a><span class="lineno">   43</span>&#160;The following example shows a simple application that will run without a window in the background until you press the key-combination &lt;kbd&gt;Ctrl&lt;/kbd&gt;+&lt;kbd&gt;Alt&lt;/kbd&gt;+&lt;kbd&gt;Q&lt;/kbd&gt; (&lt;kbd&gt;⌘&lt;/kbd&gt;+&lt;kbd&gt;⌥&lt;/kbd&gt;+&lt;kbd&gt;Q&lt;/kbd&gt; on Mac). This will quit the application. The debug output will tell if the hotkey was successfully registered and that it was pressed.</div><div class="line"><a name="l00044"></a><span class="lineno">   44</span>&#160;```cpp</div><div class="line"><a name="l00045"></a><span class="lineno">   45</span>&#160;#include &lt;QHotkey&gt;</div><div class="line"><a name="l00046"></a><span class="lineno">   46</span>&#160;#include &lt;QApplication&gt;</div><div class="line"><a name="l00047"></a><span class="lineno">   47</span>&#160;#include &lt;QDebug&gt;</div><div class="line"><a name="l00048"></a><span class="lineno">   48</span>&#160;</div><div class="line"><a name="l00049"></a><span class="lineno">   49</span>&#160;int main(int argc, char *argv[])</div><div class="line"><a name="l00050"></a><span class="lineno">   50</span>&#160;{</div><div class="line"><a name="l00051"></a><span class="lineno">   51</span>&#160;   QApplication a(argc, argv);</div><div class="line"><a name="l00052"></a><span class="lineno">   52</span>&#160;</div><div class="line"><a name="l00053"></a><span class="lineno">   53</span>&#160;   auto hotkey = new QHotkey(QKeySequence(&quot;ctrl+alt+Q&quot;), true, &amp;a);//The hotkey will be automatically registered</div><div class="line"><a name="l00054"></a><span class="lineno">   54</span>&#160;   qDebug() &lt;&lt; &quot;Is Registered: &quot; &lt;&lt; hotkey-&gt;isRegistered();</div><div class="line"><a name="l00055"></a><span class="lineno">   55</span>&#160;</div><div class="line"><a name="l00056"></a><span class="lineno">   56</span>&#160;   QObject::connect(hotkey, &amp;QHotkey::activated, qApp, [&amp;](){</div><div class="line"><a name="l00057"></a><span class="lineno">   57</span>&#160;       qDebug() &lt;&lt; &quot;Hotkey Activated - the application will quit now&quot;;</div><div class="line"><a name="l00058"></a><span class="lineno">   58</span>&#160;       qApp-&gt;quit();</div><div class="line"><a name="l00059"></a><span class="lineno">   59</span>&#160;   });</div><div class="line"><a name="l00060"></a><span class="lineno">   60</span>&#160;</div><div class="line"><a name="l00061"></a><span class="lineno">   61</span>&#160;   return a.exec();</div><div class="line"><a name="l00062"></a><span class="lineno">   62</span>&#160;}</div><div class="line"><a name="l00063"></a><span class="lineno">   63</span>&#160;```</div><div class="line"><a name="l00064"></a><span class="lineno">   64</span>&#160;</div><div class="line"><a name="l00065"></a><span class="lineno">   65</span>&#160;**Note:** You need the .pri include for this to work.</div><div class="line"><a name="l00066"></a><span class="lineno">   66</span>&#160;</div><div class="line"><a name="l00067"></a><span class="lineno">   67</span>&#160;### Testing</div><div class="line"><a name="l00068"></a><span class="lineno">   68</span>&#160;By running the example in `./HotkeyTest` you can test out the QHotkey class. There are 4 sections:</div><div class="line"><a name="l00069"></a><span class="lineno">   69</span>&#160;- **Playground:** You can enter some sequences here and try it out with different key combinations.</div><div class="line"><a name="l00070"></a><span class="lineno">   70</span>&#160;- **Testings:** A list of selected hotkeys. Activate it and try out which ones work for you (*Hint:* Depending on OS and keyboard layout, it&#39;s very possible that a few don&#39;t work).</div><div class="line"><a name="l00071"></a><span class="lineno">   71</span>&#160;- **Threading:** Activate the checkbox to move 2 Hotkeys of the playground to seperate threads. It should work without a difference.</div><div class="line"><a name="l00072"></a><span class="lineno">   72</span>&#160;- **Native Shortcut**: Allows you to try out the direct usage of native shortcuts</div><div class="line"><a name="l00073"></a><span class="lineno">   73</span>&#160;</div><div class="line"><a name="l00074"></a><span class="lineno">   74</span>&#160;### Logging</div><div class="line"><a name="l00075"></a><span class="lineno">   75</span>&#160;By default, QHotkey prints some warning messages if something goes wrong (For example, a key that cannot be translated). All messages of QHotkey are grouped into the [QLoggingCategory](https://doc.qt.io/qt-5/qloggingcategory.html) `&quot;QHotkey&quot;`. If you want to simply disable the logging, call the folling function somewhere in your code:</div><div class="line"><a name="l00076"></a><span class="lineno">   76</span>&#160;```cpp</div><div class="line"><a name="l00077"></a><span class="lineno">   77</span>&#160;QLoggingCategory::setFilterRules(QStringLiteral(&quot;QHotkey.warning=false&quot;));</div><div class="line"><a name="l00078"></a><span class="lineno">   78</span>&#160;```</div><div class="line"><a name="l00079"></a><span class="lineno">   79</span>&#160;This will turn all warnings of QHotkey of (It only uses warnings for now, thats why this is enough). For more information about all the things you can do with the logging categories, check the Qt-Documentation</div><div class="line"><a name="l00080"></a><span class="lineno">   80</span>&#160;</div><div class="line"><a name="l00081"></a><span class="lineno">   81</span>&#160;## Thread saftey</div><div class="line"><a name="l00082"></a><span class="lineno">   82</span>&#160;The QHotkey class itself is reentrant - wich means you can create as many instances as required on any thread. This allows you to use the QHotkey on all threads. **But** you should never use the QHotkey instance on a thread that is different from the one the instance belongs to! Internally the system uses a singleton instance that handles the hotkey events and distributes them to the QHotkey instances. This internal class is completley threadsafe.</div><div class="line"><a name="l00083"></a><span class="lineno">   83</span>&#160;</div><div class="line"><a name="l00084"></a><span class="lineno">   84</span>&#160;However, this singleton instance only runs on the main thread. (One reason is that some of the OS-Functions are not thread safe). To make threaded hotkeys possible, the critical functions (registering/unregistering hotkeys and keytranslation) are all run on the mainthread too. The QHotkey instances on other threads use `QMetaObject::invokeMethod` with a `Qt::BlockingQueuedConnection`.</div><div class="line"><a name="l00085"></a><span class="lineno">   85</span>&#160;</div><div class="line"><a name="l00086"></a><span class="lineno">   86</span>&#160;For you this means: QHotkey instances on other threads than the main thread may take a little longer to register/unregister/translate hotkeys, because they have to wait for the main thread to do this for them. **Important:** there is however, one additional limitation that comes with that feature: QHotkey instances on other threads but the main thread *must* be unregistered or destroyed *before* the main eventloop ends. Otherwise, your application will hangup on destruction of the hotkey. This limitation does not apply for instances on the main thread. Furthermore, the same happens if you change the shortcut or register/unregister before the loop started, until it actually starts.</div><div class="line"><a name="l00087"></a><span class="lineno">   87</span>&#160;</div><div class="line"><a name="l00088"></a><span class="lineno">   88</span>&#160;## Documentation</div><div class="line"><a name="l00089"></a><span class="lineno">   89</span>&#160;The documentation is available as release and on [github pages](https://skycoder42.github.io/QHotkey/).</div><div class="line"><a name="l00090"></a><span class="lineno">   90</span>&#160;</div><div class="line"><a name="l00091"></a><span class="lineno">   91</span>&#160;The documentation was created using [doxygen](http://www.doxygen.org). It includes an HTML-documentation and Qt-Help files that can be included into QtCreator (QtAssistant) to show F1-Help (See [Adding External Documentation](https://doc.qt.io/qtcreator/creator-help.html#adding-external-documentation) for more details).</div><div class="line"><a name="l00092"></a><span class="lineno">   92</span>&#160;</div><div class="line"><a name="l00093"></a><span class="lineno">   93</span>&#160;## Technical</div><div class="line"><a name="l00094"></a><span class="lineno">   94</span>&#160;### Requirements</div><div class="line"><a name="l00095"></a><span class="lineno">   95</span>&#160; - Explicit support is only given down to the latest Qt LTS, but may work with earlier versions, too</div><div class="line"><a name="l00096"></a><span class="lineno">   96</span>&#160; - At least the QtGui-Module (a QGuiApplication). Hotkeys on console based applications are not supported (By the operating systems). You can however create a gui application without any visible window.</div><div class="line"><a name="l00097"></a><span class="lineno">   97</span>&#160; - C++11</div><div class="line"><a name="l00098"></a><span class="lineno">   98</span>&#160;</div><div class="line"><a name="l00099"></a><span class="lineno">   99</span>&#160;### Known Limitations</div><div class="line"><a name="l00100"></a><span class="lineno">  100</span>&#160; - Only single key/modifier combinations are possible. If using QKeySequence, only the first key+modifier of the sequence will be used.</div><div class="line"><a name="l00101"></a><span class="lineno">  101</span>&#160; - Qt::Key makes no difference between normal numbers and the Numpad numbers. Most keyboards however require this. Thus, you can&#39;t register shortcuts for the numpad, unless you use a native shortcut.</div><div class="line"><a name="l00102"></a><span class="lineno">  102</span>&#160; - Supports not all keys, but most of the common ones. There are differences between platforms and it depends on the Keyboard-Layout. &quot;Delete&quot;, for example, works on windows and mac, but not on X11 (At least on my test machines). I tried to use OS-Functions where possible, but since the Qt::Key values need to be converted into native keys, there are some limitations. I can use need such a key, try using the native shortcut.</div><div class="line"><a name="l00103"></a><span class="lineno">  103</span>&#160; - The registered keys will be &quot;taken&quot; by QHotkey. This means after a hotkey was cosumend by your application, it will not be sent to the active application. This is done this way by the operating systems and cannot be changed.</div><div class="line"><a name="l00104"></a><span class="lineno">  104</span>&#160;- If you get a `QHotkey: Failed to register hotkey. Error: BadAccess (attempt to access private resource denied)` error on X11, this means you are trying to register a hotkey that is private to X11. Those keys simply cannot be registered using the normal API</div></div><!-- fragment --></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Sun Mar 11 2018 00:05:42 for QHotkey by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.14
</small></address>
</body>
</html>
